/*********************************************************
   Copyright: (C) 2008-2010 by Steven Schveighoffer.
              All rights reserved

   License: Boost Software License version 1.0

   Permission is hereby granted, free of charge, to any person or organization
   obtaining a copy of the software and accompanying documentation covered by
   this license (the "Software") to use, reproduce, display, distribute,
   execute, and transmit the Software, and to prepare derivative works of the
   Software, and to permit third-parties to whom the Software is furnished to
   do so, all subject to the following:

   The copyright notices in the Software and this entire statement, including
   the above license grant, this restriction and the following disclaimer, must
   be included in all copies of the Software, in whole or in part, and all
   derivative works of the Software, unless such copies or derivative works are
   solely in the form of machine-executable object code generated by a source
   language processor.

   THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
   IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
   FITNESS FOR A PARTICULAR PURPOSE, TITLE AND NON-INFRINGEMENT. IN NO EVENT
   SHALL THE COPYRIGHT HOLDERS OR ANYONE DISTRIBUTING THE SOFTWARE BE LIABLE
   FOR ANY DAMAGES OR OTHER LIABILITY, WHETHER IN CONTRACT, TORT OR OTHERWISE,
   ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER
   DEALINGS IN THE SOFTWARE.

**********************************************************/
module dcollections.model.Set;
public import dcollections.model.Addable;

/**
 * A set is a collection of objects where only one instance of a given item
 * is allowed to exist.  If you add 2 instances of an item, only the first
 * is added.
 */
interface Set(V) : Addable!V, Iterator!V, Purgeable!V
{
    /**
     * Remove all values that match the given iterator.
     */
    Set remove(Iterator!(V) subset);

    /**
     * Remove elements from the set.  Guaranteed to be O(lgN) or better.
     */
    Set remove(V[] values...);

    version(testcompiler)
    {

    /**
     * Remove all the values that are in the given range.
     * returns this.
     * TODO: rename to remove
     */
    auto removeRange(R)(R range) if (isInputRange!R && is(ElementType!R == V))
    {
        bool wasRemoved;
        foreach(v; range)
            remove(v, wasRemoved);
        return this;
    }
    }

    /**
     * Remove all value that are not in the given iterator.
     */
    Set intersect(Iterator!(V) subset);

    /**
     * Remove all value that are not in the given element list.
     */
    Set intersect(V[] subset...);

    /**
     * dup (part of collection pseudo-interface)
     */
    Set dup();

    /**
     * Returns true if the given value exists in the collection. Guaranteed to
     * be O(lgN) or better.
     */
    bool contains(const(V) v) const;

    /**
     * Covariant add (from Addable)
     */
    Set add(V[] elems...);

    /**
     * Covariant add (from Addable)
     */
    Set add(Iterator!(V) it);

    /**
     * Compare two sets.  Returns true if both sets have the same number of
     * elements, and all elements in one set exist in the other set.
     *
     * if o is not a Set, return false.
     */
    bool opEquals(Object o);

    /**
     * get the most convenient element in the set.  This is the element that
     * would be iterated first.  Therefore, calling get() is
     * guaranteed to be an O(1) operation.
     */
    @property inout(V) get() inout;

    /**
     * Remove the most convenient element from the set, and return its value.
     * Note that this may not be the same element as returned by get.
     * Guaranteed to be O(lgN) or better.
     */
    V take();
}
